package com.helin.helinhealth.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.helin.helinhealth.entity.Medicine;
import org.apache.ibatis.annotations.Param;

import java.util.List;

/**
 * 药品Mapper接口
 * 
 * <p>
 * 该接口负责药品相关的数据库操作，继承自MyBatis-Plus的BaseMapper，
 * 除了默认的CRUD方法外，还添加了一些自定义的查询方法。
 * 具体SQL实现在对应的XML映射文件中。
 * </p>
 * 
 * <p>
 * 自定义方法主要用于获取用户的药品列表、今日需服用的药品和库存低的药品等，
 * 以支持药品管理和服药提醒功能。
 * </p>
 */
public interface MedicineMapper extends BaseMapper<Medicine> {
    /**
     * 获取用户的药品列表
     * 
     * <p>
     * 查询指定用户的所有未删除药品，按创建时间降序排序。
     * 主要用于展示用户的药品管理列表。
     * </p>
     *
     * @param userId 用户ID（openid）
     * @return 药品列表
     */
    List<Medicine> getUserMedicineList(@Param("userId") String userId);
    
    /**
     * 获取今日需服用的药品
     * 
     * <p>
     * 查询指定用户今日尚未服用的药品，按服药时间升序排序。
     * 用于实现服药提醒功能，在首页展示待服用的药品。
     * </p>
     *
     * @param userId 用户ID（openid）
     * @return 今日需服用的药品列表
     */
    List<Medicine> getTodayMedicines(@Param("userId") String userId);
    
    /**
     * 获取即将用完的药品
     * 
     * <p>
     * 查询指定用户库存天数低于阈值的药品，按库存天数升序排序。
     * 用于提醒用户及时补充药品，防止断药。
     * </p>
     *
     * @param userId 用户ID（openid）
     * @param threshold 库存阈值（天）
     * @return 库存低的药品列表
     */
    List<Medicine> getLowStockMedicines(@Param("userId") String userId, @Param("threshold") Integer threshold);
    
    /**
     * 更新药品服用状态
     * 
     * <p>
     * 更新指定药品的服用状态，使用乐观锁机制防止并发更新。
     * 在用户进行服药打卡时使用此方法。
     * </p>
     *
     * @param id 药品ID
     * @param isTaken 是否已服用
     * @param version 乐观锁版本号
     * @return 更新成功的记录数，0表示更新失败
     */
    int updateMedicineTakenStatus(@Param("id") Long id, @Param("isTaken") Boolean isTaken, @Param("version") Integer version);
}
